# MWRhythm v1.0.2

MWRhythm is a rhythm "minigame" mod built for **Need for Speed: Most Wanted (2005)**.

This project is a fork of **CarbonRhythm**, originally created for **Need for Speed: Carbon**, and has been ported to **Need for Speed: Most Wanted**.

---

## Features

* 6-lane rhythm input system
* Car animations
* Beat-based scrolling notes
* Dynamic BPM support
* Judgement system (Perfect / Good / Bad / Miss)
* Combo and multiplier system
* Accuracy calculation
* Custom beatmap support
* Autoplay mode
* Hit sounds
* Visual overlay with animated UI elements
* Beatmap recorder

---

## v1.0.2 Update Notes

* Added Dynamic BPM support.
  Beatmaps can now define a `bpmChanges` array to change BPM while the song is playing.

* Added beat-based note scrolling.
  Notes now scroll based on beat distance instead of raw seconds, which helps prevent note jumps around BPM changes.

* Added Autoplay mode.
  Autoplay simulates lane inputs and blocks player rhythm input while enabled.

* Added configurable Autoplay key.
  Default key is **F1**, controlled by `AutoplayToggle` in the config file.

* Added hit sounds.
  Perfect / Good / Bad hits play `CarbonRhythmAssets/CRsoft.mp3`.
  Misses remain silent.

* Added optional jelly BPM sync.
  The car jelly animation can follow the current BPM, including dynamic BPM changes.
  This can be turned off in the config file.

* Fixed spin restart behavior.
  Starting a slow spin now cancels any active quick spin state.
  Starting a quick spin now cancels any active slow spin state.
  This prevents an interrupted spin from resuming after the new spin finishes.

---

## HOW TO'S

## Install & Play

1. Extract the files from the zip to the root folder of your game.
2. In game, press **F2** to show the mod's menu.
3. Use **IJKL** keys for menu navigation:

   * **I / K** for Up / Down
   * **J / L** for Return / Enter

4. Use **IJKLUO** keys for playing.

Default lane keys:

* Lane 1 - U
* Lane 2 - J
* Lane 3 - K
* Lane 4 - I
* Lane 5 - L
* Lane 6 - O

Also make sure you turn all in-game music off for a better experience.

---

## Change Configurations

1. Open `scripts/CarbonRhythm.ini`.
2. Configure keys if needed.
   You can look up Virtual-Key Codes on Google.
3. Configure beatmap recording settings if needed.
4. If you want to edit the config without restarting the game, use the **Reload Config** option in the mod's menu.

Important v1.0.2 config options:

```ini
[Keybinds]
AutoplayToggle=112   ; F1
```

```ini
[Dance]
SyncJellyToCurrentBPM=1
```

`SyncJellyToCurrentBPM=1` means the car jelly animation follows the current BPM.

`SyncJellyToCurrentBPM=0` means normal beatmap playback uses the beatmap JSON `dance.jellyBPM` value, which is the old behavior.

`JellyBPM` in the ini is mainly used by the beatmap recorder and is saved into newly recorded beatmap JSON files.

---

## Autoplay

Autoplay is toggled with **F1** by default.

You can change the key in:

```ini
[Keybinds]
AutoplayToggle=112
```

When Autoplay is active, player rhythm input is blocked and the mod simulates the required lane inputs.

Autoplay is useful for testing beatmaps and visual timing. Very dense note sections may still need more tuning.

---

## Hit Sounds

Hit sounds play on:

* Perfect
* Good
* Bad

Misses are silent.

The sound file should be placed here:

```text
CarbonRhythmAssets/CRsoft.mp3
```

---

## Dynamic BPM Beatmaps

Dynamic BPM is optional.

Old beatmaps without `bpmChanges` still work normally and use the fixed top-level `bpm` value.

Example:

```json
{
    "bpm": 130.0,
    "bpmChanges": [
        {
            "time": 0.0,
            "bpm": 130.0
        },
        {
            "time": 30.0,
            "bpm": 80.0
        },
        {
            "time": 60.0,
            "bpm": 180.0
        }
    ]
}
```

`time` is measured in seconds from the start of the song.

New dynamic BPM beatmaps require v1.0.2 or newer for correct behavior.
Older versions may still load the file, but they will ignore `bpmChanges` and treat the whole song as fixed BPM.

---

## Record Custom Beatmap

1. Open the `scripts/CarbonRhythm.ini` file.

2. Put your audio file in the `CarbonRhythmAssets/maps/` folder.
   MP3 is recommended.

3. Go to `CarbonRhythm.ini`, then put your audio path and file name in the `AudioPath` option under `[Recorder]`.

4. Put your preferred output beatmap name in `OutputName`.

5. Find out the BPM of the song.
   You can usually search for `"<song name> BPM"` on Google.

6. Put the BPM value in `BPM`.

7. Put your preferred recorder jelly BPM in `JellyBPM`.
   This value will be saved into the generated beatmap JSON.

8. If your song has an audio offset, such as a delayed start or an intro that does not begin exactly on beat, put the offset value in `Offset`.

9. Put your preferred quantization division if needed.
   A value of `4` is fine for most songs.

   If:

   * the song has fluctuating tempo / BPM,
   * you want full control of where your notes land, or
   * your audio is not aligned to the beat,

   you can simply put `0` to disable quantization.

10. Configure difficulty settings, including beat windows for scoring and judgement, if needed.

11. Configure your Dance Settings, which control how the car dances, if needed.

12. Configure metadata if needed, including Title, Artist, and Difficulty.
    These will show up in the Beatmap Select menu.

13. In the mod menu, reload the config if you do not want to restart the game.

14. Go to the Beatmap Recording menu.

15. If all the settings shown in game are correct, press **ENTER** to start recording.

16. When you are done, press **F4** to stop recording.

17. Check the Beatmap Select menu.
    Your new beatmap should be shown automatically.

---

## Controls

Default lane keys:

* Lane 1 - U
* Lane 2 - J
* Lane 3 - K
* Lane 4 - I
* Lane 5 - L
* Lane 6 - O

Key bindings may depend on your game input configuration.

---

## Included Beatmaps

Included beatmaps may depend on the release package.

---

## Notes

* This mod is made for the PC version of **Need for Speed: Most Wanted (2005)**.
* This mod is still in development, so bugs or issues may occur.
* Since this is a fork and port of CarbonRhythm, some behavior may still be adjusted in future versions.

---

## Troubleshooting

If the mod does not load:

* Ensure you are using the correct game version.
* Ensure the files were extracted to the correct game root folder.
* Ensure you have Microsoft Visual C++ x86 Redistributable installed.
* If Widescreen Fix or ExOpts works in your game, this mod should usually be able to load as well.

If beatmaps do not appear:

* Ensure beatmap JSON files are in `CarbonRhythmAssets/maps/`.
* Ensure the beatmap JSON is valid.
* Ensure the referenced audio file exists.

If hit sounds do not play:

* Ensure `CarbonRhythmAssets/CRsoft.mp3` exists.

---

## Disclaimer

This project is a fan-made modification.
Need for Speed: Most Wanted is owned by Electronic Arts.
This mod is not affiliated with or endorsed by EA Games.

---

## Credits & Thanks

* giovannosaur / nismofan - Original author of CarbonRhythm
* ThirteenAG - Ultimate ASI Loader
* Zolika1351 - NFSC-SDK references
* MinHook - Hooking library
* nlohmann/json - JSON library
* BASS Audio Library - Audio playback support
* ShifterSC & Szymkim2134 - Later maintenance and feature contributions
* Lee-Ryo - Special thanks for creating the new UI skin

---

## License

MinHook is licensed under the BSD 2-clause license.
nlohmann/json is licensed under the MIT license.
BASS is free for non-commercial use.
